1
2
3
4
5
6
7 package ca.uhn.cache;
8
9 /***
10 * A query parameter that is relevant for caching, i.e. that describes
11 * the limits of the query scope along some dimension in a <code>IParamSpace</code>.
12 *
13 * @author <a href="mailto:bryan.tripp@uhn.on.ca">Bryan Tripp</a>
14 * @version $Revision: 1.1 $ updated on $Date: 2005/01/24 22:52:08 $ by $Author: bryan_tripp $
15 */
16 public interface IQueryParam {
17
18 /***
19 * @return the dimension in parameter space to which this
20 * <code>IQueryParam</code> belongs
21 */
22 public IDimension getDimension();
23
24 /***
25 * @param theParam an <code>IQueryParam</code> along the same dimension as this one
26 * @return true iff the given param intersects with this (for example contains,
27 * is part of, overlaps)
28 *
29 * @precondition theParam != null
30 */
31 public boolean intersects(IQueryParam theParam);
32
33 /***
34 * @param theParam another IQueryParam
35 * @param theSaturationPoint distances are normalized (see below) to between zero
36 * and 1. This arg is an IQueryParam that indicates what corresponds to a distance
37 * of 1 from the origin. For example consider a date-related dimension in which dates
38 * over the last week are relevant. The origin would be now, and the saturation
39 * point would be one week ago. This parameter can be ignored, and is allowed
40 * to be null, for dimensions that are not ordered.
41 * @return the distance between this IQueryParam and the other. The distance
42 * is a number between 0 and 1. It is zero if the two IQueryParam intersect,
43 * and 1 if they are at opposite ends of an ordered dimension. For dimensions
44 * that correspond to some natural ordering, the distance should increase
45 * monotonically with the difference in the ordering property (e.g. with an alphabetical
46 * dimension, there should be a greater distance between the A chunk and the C chunk
47 * than between A and B chunks). For non-ordered dimensions, the distance
48 * between any two non-intersecting IQueryParam may be the same.
49 * X.getDistance(Y) == Y.getDistance(X).
50 * @throws IllegalArgumentException if the given IQueryParam belongs
51 * to a different dimension
52 */
53 public float getDistance(IQueryParam theParam, IQueryParam theSaturationPoint);
54
55 /***
56 * @param theParam another IQueryParam
57 * @return the result of merging this IQueryParam with the other. This is not
58 * necessarily a union. If the dimension has an ordering then the result
59 * must encompass all points in both IQueryParam as well as points in
60 * between.
61 * @throws IllegalArgumentException if the given IQueryParam belongs
62 * to a different dimension
63 */
64 public IQueryParam merge(IQueryParam theParam);
65
66 }